Die Ultimative Software-Pakete CD-ROM fur Atari Collection 1996 & 1997

home *** CD-ROM | disk | FTP | other *** search

/ Die Ultimative Software-P…i Collection 1996 & 1997 / Die Ultimative Software-Pakete CD-ROM fur Atari Collection 1996 & 1997.iso / p / portfoli / small_c / prg.man < prev next >

Wrap

Text File | 1996-10-30 | 165.5 KB | 5,160 lines

ii iiii ii sss cccc ssssssss cccccccc iiiii sss sss ccc ccc iiiii sssss ccc iii sssss ccc iii sssss ccc iii sss sss ccc ccc iii ssssssss cccccccc iiiiiiiii ssss cccc iiiiiiiii Small C Interpreter Version 1.3 for MS-DOS Copyright (C) 1986 Bob Brodt Programmer's Manual Small C Interpreter Programmer's Manual 1. Introduction to SCI Programming This section of the manual is a tutorial introduction to the C language. If you have a casual knowledge of BASIC and understand some of the fundamental concepts of programming, you should have no difficulty in following along. This tutorial is designed to be used along with SCI, so get out your working copy of the SCI distribution diskette. You did make a backup copy, didn't you? If not, DO NOT PASS GO, DO NOT COLLECT $200 until you've read and followed the instructions in the Introduction section of the SCI User's Manual! Now go ahead and start up SCI. The interpreter should be loading the default "shell" file, SHELL.SCI. This file simply contains a C program that is run by the SCI interpreter. It performs several functions (most of which shall remain invisible to you for the moment), but the most important is to allow you to write and test SCI programs immediately. After the interpreter has started up, you should see SCI's program identification banner and a greater-than symbol (>), like this: A> SCI Small C Interpreter, V1.3 15Mar86 Copyright (C) 1986 Bob Brodt Small C Shell, V1.3 15Mar86 Copyright (C) 1986 Bob Brodt > The ">" tells you that SCI is now ready to accept input from you. One of the nicest features of SCI is its ability to immediately perform any C statement that you type. As you will learn later, every C statement produces a value as a side-effect. One of the functions of SHELL.SCI is to print this value as a decimal number after the statement has been executed. Thus, you could enter some arithmetic expression like the following: > 2+2; 4 > and have the SCI shell print the result, just like BASIC. - 1 - Small C Interpreter Programmer's Manual 2. SCI Statement Structure In the above example, notice the semicolon at the end of the line. The C language allows you to write programs without regard to "white space" (spaces, tabs and ends of lines). This means that the components of program statements can be seperated by as many spaces or tabs as you like; program lines can be grouped together seperated from the rest of the program by blank lines, to show the reader that they perform a discrete function; you can indent groups of lines following a program looping statement to show where the loop starts and ends. By allowing you to "sculpture" your program like this, C lets you write very easy to read and understand programs. This is very much in contrast to BASIC which requires every program statement to start with a line number, followed by a space and then the statement all on a single line. Because C is such a free-form language it would have a difficult time recognizing the end of a statement without some kind of "end-of-statement" marker. This is the purpose of the semicolon. Now we're going to confuse you even further by telling you that SCI doesn't need a semicolon at the end of a statement! Because it's an interpreter, SCI recognizes either the end of a line or a semicolon as an end-of-statement marker. In fact, if a statement spills over onto another program line, SCI will complain - it requires that every statement be completely contained on one line. This restriction was imposed by the fact that SCI is an interpreter and not a compiler. This is an important difference between "SCI C" and "standard C" (which allows a single statement to be spread out over several lines). So if you are an experience "C hacker", please be aware of this fact. - 2 - Small C Interpreter Programmer's Manual 3. SCI Program Structure When learning a new programming language, it's always helpful to recall fundamentals and ask yourself the question "what is a program?". Simply stated, a program is a list of instructions that tell the computer exactly what to do. A program written in the BASIC language is an ideal example of this concept; a list of instructions. The instructions are numbered to make it easy to see the order in which they'll be performed. Let's examine a fragment from a BASIC program and identify some of its key components. 100 REM *** sort a list of numbers in ascending order *** 110 DIM NUM(100),RSP$(80) 120 REM get the unsorted number list . . . 220 REM got 'em, now sort 'em then print 'em 230 GOSUB 500 240 FOR I=1 TO 100 250 PRINT NUM(I) 260 NEXT I 270 PRINT "Got another list to sort?"; 280 INPUT RSP$ 290 IF RSP$="Y" THEN GOTO 120 300 END 500 REM *** bubble sort routine *** 510 REM sorts the numbers in the array "NUM" . . . 600 RETURN Even the novice BASIC programmer can glance at this program fragment and tell what's happening: it starts with line 100, which is a note to the (human) reader telling him what the program intends to do - sort a bunch of numbers in ascending order. Line 110 tells the computer to reserve some memory storage we'll need later. Remember that BASIC allows variables to be "known" to every instruction in the program. Thus, you (the programmer) can not effectively control and limit access to variables. This makes it difficult at times to determine where in the program a variable is being set when it shouldn't be. This is a very important difference between BASIC and C, as you will find out later. The word "GOSUB" at line 230 tells the computer to hold - 3 - Small C Interpreter Programmer's Manual its place at the current location in the program, then jump to instruction number 500. The "RETURN" at line 600 corresponds to the "GOSUB" and tells the computer to continue with the instruction following the "GOSUB". Notice that the set of instructions from line 500 to 600 are general-purpose in nature and could possibly be used in another BASIC program that required a number sorting function. However, to interface this sub-program to another program would probably require modifications to either the other program or the sub-program, or both. This makes the thought of extracting the number sorting function somewhat less attractive. Now look at the instructions from line 270 to 290. Essentially, these ask the program user if there are any more numbers to sort, and jump back to the beginning of the program to start the process all over again. But, what if the programmer decides at some later time to modify the program and accidentally deletes line 120 - the target of the "GOTO" instruction at 290. BASIC would be totally confused, since it wouldn't be able to find line 120 anymore. Although numbering program instructions, like BASIC does, is very nice and neat and makes a program easy for the human reader to follow, it can become unmanageable as the program grows in complexity. Now let's take a look at the comparable program fragment written in C. Please don't be concerned with the details of this program at the moment, but rather focus on the overall structure: # *** sort a list of numbers in ascending order *** main() { char num[100], rsp[80]; while ( 1 ) { # get the unsorted number list . . . # got 'em, now sort 'em then print 'em sort( num ); i=0; while ( i<100 ) { printf( "%d\n", num[i] ); ++i; } puts( "Got another list to sort?" ); - 4 - Small C Interpreter Programmer's Manual gets( rsp ) if ( rsp[0] != 'Y' ) break; } } sort( numlist ) char numlist[]; { # bubble sort routine . . . } The first thing that strikes the BASIC programmer when he looks at a C program is the absence of line numbers! The C language relies purely on the location of statements within a program to determine the order of program execution. In the above example, notice the presence of the matching left and right curly braces ({ and }). These serve to bind together logical sections of the program. In particular, notice the first "{" (following "main()") and its partner towards the end of the program. These particular matching braces are used to "bind" everything between them to make one functional unit. This functional unit is called a "function" in C. Each function can be thought of as an autonomous entity - everything within the function is accessible only to statements within that function. The name of the function can be found immediately before the first "{", in this case, the function's name is "main". Another function can be found towards the end of the program, its name is "sort". So, in contrast to BASIC, a C program is a collection of these modular functions rather than just a sequential list of instructions. - 5 - Small C Interpreter Programmer's Manual 4. Functions Think of functions as a kind of "black box" machine; raw materials, in the form of information, goes into one end of the machine and a final product comes out of the other end. The inner workings of the machine are hidden and we don't really care to know how the machine works, as long as the final product is what we expected from the raw materials supplied. In C, the "raw materials" passed to a function are known as the function's "arguments" and the "final product" is called the function's "return value". C allows you to pass as many arguments to a function as needed, but the function always returns one and only one value. In the section on Variables we will see how a function can be made ____ to seem to return more than one value. To get SCI to execute the statements within a particular function, all you have to do is mention the function's name. In the program fragment shown above, you would type either "main()", or "sort()" at the SCI prompt. The parentheses following a function's name serve two purposes: they distinguish the entity as being the name of a function as opposed to a variable; and they show SCI where the function's arguments start and end. If a function does not require any arguments (as in "main()" above), you still need to supply the left and right parentheses. If a function requires more than one argument, each argument is seperated from the preceding one with a comma (,) like so: func( 23, 15, 34 ) Note that the spaces are optional! 4.1. Library Functions Beyond using it as a rather dumb integer calculator, you can use the SCI shell to test out any valid C statement with support from a large collection of built-in functions. As you work through this tutorial, you will be introduced to many of these, refered to hereafter as "Library Functions" (see the section on Library Functions for more details). You may, if you like, think of the Library Functions as being analogous to BASIC's built-in commands like "PRINT" and "INPUT". Most of the Library Functions are similar to those shipped with "industrial strength" C compilers, so - 6 - Small C Interpreter Programmer's Manual many of the programs you write under SCI should be transportable with some minor changes. 4.1.1. putd() The Library Function "putd()" prints a number, or the results of a calculation on the console screen. Try entering the following commands from the shell: putd(123) putd( 235 + 12370 ) In the first example, the argument passed to "putd()" is the number 123. The function should have printed "123" on the console screen. In the second example, the argument is the sum of 235 and 12370. Note that this calculation is performed first, then the result is passed to "putd()" for printing. Below the numbers that were printed by "putd()" you should have seen a zero printed as well. This zero is the value returned by "putd()" and was printed by the shell. In this case, the return value of a function was not particularly useful. We were more interested in the side-effect of this function, namely the displaying of a number on the screen. 4.1.2. getchar() The Library Function "getchar()" waits for a single keyboard key to be pressed, then returns the value (in ASCII) of that key. At the shell prompt, try typing "getchar()", hit a carriage return and then hit the letter 'a' key. You should see the number 97 printed by the shell, the ASCII value in decimal of the character 'a'. Unlike "putd()", this function required no arguments and returned a useful value. 4.1.3. puts() The function "puts()" is used to print a sequence of characters (known in C jargon as a "string") on the console. A string is represented in C as a bunch of - 7 - Small C Interpreter Programmer's Manual characters enclosed in quotes ("), just as in BASIC. Try the following command, and be careful to type the string exactly as it appears here: puts("hello, world\n") Look closely at the string again and notice the backslash (\) just before the letter 'n'. This two-character combination (\n) is standard C shorthand notation for a "newline" character. Newlines have the effect of performing a cariage return plus linefeed on the console. Had we omitted the "\n" from the string, "puts()" would have just printed "hello, world" and left the cursor on the same line, after the "d" in "world". SCI provides other similar shorthand notations, which will be explained in a later section. - 8 - Small C Interpreter Programmer's Manual 5. Your First Programs Now it's time to write your first program. If you haven't already done so, read the Editor section of the User's Manual and perform the installation as required for your particular computer. If you are unsuccessful in getting the editor to work properly, you can create the sample programs with your favorite text editor, then start up SCI and load the program file. This will be tedious and time consuming, but it may just give you enough understanding of C to perform the editor installation properly. If all else fails, appeal to the author for help! 5.1. Hello again, world! Either using the built-in editor or a seperate text editor, create the following program: hi() { puts("hello, world\n"); } Now, from the shell, type the name of the function, "hi()". You should see the following on your screen: > hi() hello world 0 > If instead you are rewarded with an error message followed by a question mark, you did something wrong! Hit a carriage return or two to get back to the shell's ">" prompt, go back into the editor, fix the mistake and try it again. Whether you realize it or not, this exercise is an important first step for learning a new programming language. It teaches you all of the routine motions you will be going through to write programs and gives you confidence to continue on. - 9 - Small C Interpreter Programmer's Manual 5.2. Fahrenheit to Celsius Next, type in the following sample program: fahr(celsius) { return 9 * celsius / 5 + 32; } This is a simple celsius to fahrenheit temperature conversion function. Notice here the symbols for multiplication (*) and division (/) are the same as in most other programming languages. Try executing this function with a few different celsius values. Each time the argument is converted to fahrenheit and is returned to the shell to be printed. As an exercise, modify the program to print the fahrenheit value and return a value of zero! - 10 - Small C Interpreter Programmer's Manual 6. Statements: Simple and Compound In C, a "statement" is just what you might expect; an imperative instruction to the computer to perform some calculation. Statements are generally some kind of arithmetic expression followed by a semicolon (or the end of line in SCI) - we have encountered them before. The C language also allows you to group together several of these "simple" statements and treat them as a single "compound" statement. This is done by placing left and right curly braces ({ and }) around the simple statements. Let's look at the example below: {puts("hello");puts("world\n");} Here, everything within the left and right braces and the braces themselves are treated as a single statement in C. The C language also lets us write the above statement like this: { puts( "hello" ); puts( "world\n" ); } Notice that the program becomes much easier to read when each statement is written on a seperate line. Also notice that we have indented the two simple statements from the braces. Indenting is the accepted way of conveying the intended structure of a program. We are in effect saying that these two lines "belong together" and should be treated as a single unit. The compound statement in the above example was obviously created for demonstration purposes only. If it had been encountered by itself in a real program, the braces would have been superfluous and would not have altered the behavior of the program. However, earlier we encountered an instance where the curly braces were required, namely immediately following a function definition. Later on when we discuss program flow control, we will again sing the praises of compound statements. We will now make just one more point concerning compound statements and the SCI shell. From the shell, type the following two statements: - 11 - Small C Interpreter Programmer's Manual > puts("hello"); puts(" world"); > {puts("hello"); puts(" world);} In the first instance, you saw that only the word "hello" was printed followed by the shell's ">" prompt. This is because the interpreter executes only the first statement it finds in the input line buffer. Since a statement is terminated by a semicolon, the second call to "puts" was never seen. In the second example, the interpreter saw the left curly brace, recognized the entire line as a single statement, and executed both calls to "puts()". 6.1. Comment Statements Comment statements are completely ignored by C and may be used liberally anywhere within a program for documentation purposes. Standard C uses the two-character combinations /* (pronounced "slash-star") and */ to mark the beginning and ending of comment statements: 2 + /* this is a comment */ 2 + 2; The /* and */ need not necessarily be on the same program line, as for example: 2 + 2 + 2; /* this is a comment */ SCI uses the number symbol (#) to introduce comment statements. A comment in SCI begins with a # and ends at the end of the line. Being an interpreter, SCI required that comments appear on a single line, so only a comment start symbol was required. The above example might appear in SCI like this: 2 + 2 + 2; # # this is a comment # - 12 - Small C Interpreter Programmer's Manual Be careful when placing comments because everything to the right of the first # symbol on the line is ignored by SCI. 2 + # this is a comment # 2 + 2; - 13 - Small C Interpreter Programmer's Manual 7. Expressions Expressions can be thought of as components of a C statement - the values and operators that, when evaluated, yield a result. The most common example that comes to mind are arithmetic expressions: 2 + 3 - 5 An expression becomes a statement if we simply tack a semicolon at the end of it, thus: 2 + 3 - 5; 7.1. Operators Since C provides a plethora of operators, we will not discuss them all in this section but rather introduce them as they become relavent to the discussion. If you have burning desire to discover all of C's operators, see the Appendix. First, we will define some commonly used terms. 7.1.1. Binary Operators The term "binary operator" does not refer to bits and bytes but rather to the class of operators that require two (hence "binary") operands. Some of these you have probably already seen if you are familiar with other programming languages, like the addition (+), subtraction (-), multiplication (*) and division (/) operators. 7.1.2. Unary Operators Unary operators perform their functions on only one operand. The subtraction symbol (-) is used as a unary operator when it stands in front of a number or a variable, like so: -45 - 14 - Small C Interpreter Programmer's Manual You may also use the plus sign (+) as a unary operator, although it would be superfluous since all numbers are assumed to be positive unless preceeded by a minus sign. C also provides other unary operators that will be discussed later. 7.2. Precedence If you will recall, in your high school algebra class you learned that in an arithmetic expression containing a combination of addition, subtraction, division and multiplication, the division and multiplication are always done before addition and subtraction. That is to say that division and multiplication "take precedence" over addition and subtraction. This property of precedence extends to all operators in the C language, not just the arithmetic operators. You may defeat the normal order of evaluation of an expression by using parentheses, just as in modern algebra: (2 + 3) * 5 This will perform the addition first, then the multiplication. You may use as many matched sets of parentheses as necessary to disambiguate the order of evaluation: ( ( (2+3) / 2 ) * 5 ) In fact, it is a good idea to use parentheses liberally whenever you are unsure of operator precedence. 7.3. Associativity You also learned (hopefully in the same algebra class) that expressions are always evaluated from left to right. This same rule applys to expressions in C. This property of operators is known as associativity. In C, most of the ____ ____ __ _____ binary operators are evaluated from left to right, while the _____ __ ____ unary operators are evaluated from right to left. - 15 - Small C Interpreter Programmer's Manual 7.4. Arithmetic operators Now we are finally prepared to formally introduce C's arithmetic operators. They are listed here in order of decreasing precedence: * / % multiplication, division and modulo + - addition and subtraction Most of these should already be familiar to you. The modulo operator (%) gives the remainder from the division of the left value by the right value. For example, the result of: 15 % 8 is 7. 7.5. Bitwise Operators C also offers these bit-manipulation operators (again listed in decreasing precedence): << >> left and right SHIFT & bitwise AND ^ bitwise exclusive OR | bitwise OR If you have a need to do bit manipulation but are not familiar with the above terms (SHIFT, AND, OR and exclusive OR), you should probably consult a textbook on computer programming since this is beyond the scope of this tutorial. We will be learning more about other C operators in later discussions. - 16 - Small C Interpreter Programmer's Manual 8. Variables Previously, we had only eluded to the fact that C does allow you to create named data storage locations (a.k.a. "variables"), now we will formally introduce you to all of C's data types. Except for the pre-defined Library Functions and the editor's system-variables (which are found in SHELL.SCI), all variables must first be made known to the program before they may be used. Unlike BASIC where a variable comes into existance the very first time it is used in a statement, C requires that every variable be formally declared before you may use it within your program. This section will cover the fundamentals of C variable declarations. 8.1. Naming Conventions The precise rules governing the naming of variables usually varies from one C compiler to another. The rules for SCI variable names are as follows: 1) a variable name may contain any number of characters from the set of: 1) the letters "a" through "z" and "A" through "Z". 2) the underscore (_). 3) the digits "0" through "9". 2) the first character of a variable must not be a digit (i.e. it must be either a letter or an underscore). 3) the case of a letter is significant, for example: "foobar" is not the same as "Foobar" or "FooBar". 4) although a variable may be as long as you like, only the first eight characters are signifcant. For example: "return_value" and "return_value_1" refer to the same variable, since only the first eight characters ("return_v") are significant. - 17 - Small C Interpreter Programmer's Manual 8.2. Data Types The C language supports many different types of variables. The most notable difference between them is the amount of memory storage each one addresses. The least amount of memory a variable can represent depends on the type of computer the program is written for. Typically, this is a byte of information, although some mainframe machines do not have the capability to access memory in smaller than 2 or 4 byte gobbles. Most personal computers, however can access memory one byte at a time and in C, this data type is known as the "char", short for "character". 8.2.1. Char A "char" variable in SCI is one byte long and can represent a number between -128 and +127. In order to make a variable known to the program we must first declare it, so to declare a "char" variable named "foobar" we would write: char foobar; We can also declare more than one variable of the same type on the same line by seperating each with a comma, like so: char foobar, snafu, gurgle; 8.2.2. Int Another variable type is the "int", short for "integer". Again, the amount of memory an "int" addresses is machine dependent. In SCI, an "int" addresses two bytes of memory, and can represent a number between -32768 and +32767. "Int"s are declared in a manner similar to "char"s: int foobar; int snafu, wowbagger; Standard C also defines other data types such as floating point variables, double precision integer and double precision floating point. You may also define your own data - 18 - Small C Interpreter Programmer's Manual types that are a combination of these primaries (known as "structures"). Unfortunately, these are all not supported by this version of SCI. 8.3. Scope If you are familiar with BASIC, then you already know that a BASIC program variable is "known" throughout the program - that is, any statement within the program may alter a variable's contents. This "feature" can lead to some very difficult to find programming bugs. For instance, you may use a variable as a temporary loop counter in one section of the program, only to discover later that you had already decided to use that variable for another purpose and its contents were continually being destroyed. Ideally, we would like to be able to use variable names indiscriminantly in one section of a program without having to worry about whether the variable name is being used in another section of the program. Happily, the C language offers this ability as you will soon see. This concept of limited (or rather "controlled") access to variables is known as "scope". 8.3.1. Global Variables In C, you may create variables that are known throughout the program, just like in BASIC. Variables that have this property are known as "globals" and just like BASIC, every statement within the program may retrieve and store the value of a global variable. A variable will attain global status if it was declared outside of any curly braces ({ and }) that delimit the body of a function. Here is an example to illustrate: char c; # "c" is a global int i, j; # and so are "i" and "j" a_function() # the first function in the program { . . . } char flag, nyuk; # some more global variables another_function() # another function { - 19 - Small C Interpreter Programmer's Manual . . . } As you can see, C does not care where within a program a global variable is declared as long as the declaration appears outside of any functions. SCI ensures that global variables are always set to zero before the program starts up. This is pretty much standard behavior for most C compilers as well. In C, functions are also considered to be globals - they are known throughout the program, although they obviously can't be used to store data. 8.3.2. Local Variables Variables that are declared inside of the curly braces that mark the beginning and end of a function are known as "local" variables. Locals exist only during the life of the function - that is the variable comes into existence after it has been declared within a function and ceases to exist when the function returns to its caller. See the example below for clarification: char c; # these are global variables int i; a_function() # a function definition { char snafu; # a local variable int x, y; # some more locals . . . x = c; # copy the global to a local } # snafu, x and y cease to exist! ____ Variable declarations must appear immediately after a left curly brace; if a declaration appears anywhere else within the body of a function SCI will warn you about a "syntax error". ___ In addition, variables may be declared within any ____ compound statement in a function, but the declarations must appear immediately after the opening brace. Variables - 20 - Small C Interpreter Programmer's Manual declared in this context exist only for the life of the compound statement, i.e. to the matching closing brace. Thus the memory these variables occupy can be re-used within the function. Below is an example to illustrate: func() { char a; int i; . . . if ( i==0 ) { int j; # declare an "int" in a compound stmt . . # "a", "i" and "j" are all locals here . } # "j" no longer exists here else if ( i==1 ) { char j; # a different "j" than above . . . } } SCI ensures that locals are always zero just after they have been declared. On standard C compilers, the initial contents of locals is unknown, so do not depend on them being zero. 8.3.3. Function Arguments Function arguments are also considered to be local variables. When a function calls another function and passes it an argument, the argument's contents is copied into a local variable in the called function - the value of the caller's argument is not affected. This is best illustrated with an example: char c; # the global variable, "c" func1() { char c; # a local may have the same name as a global c = 1; # and this sets the LOCAL variable "c" to 1! - 21 - Small C Interpreter Programmer's Manual func2(c); # now call func2 } func2( x ) char x; { char c; # this "c" is different from func1's "c" x = 3; # this does not affect func1's "c" c = 5; # this does not affect the global "c" } 8.3.4. System Globals As mentioned earlier, the Library Functions and the editor's configuration variables that are declared in the shell are also globals. These however, are more permanent than program globals. A program's global variables can be zapped into non-existence simply by editing the program and removing the statement that declares them. System globals can not be destroyed since SCI will not allow you to modify the shell program (or any program for that matter) while it is still running. 8.4. Location of Variables At this point it may be useful to discuss where in memory each of these different types of variables is located. Although this depends on the compiler's implementation and the hardware, most C compilers take advantage of some commonly used data structures. 8.4.1. The Stack The stack is simply a chunk of the computer's memory that can only be accessed (read from and written to) indirectly through a machine register known as the "stack pointer". If the CPU does can not provide a stack pointer register, the authors of the C compiler will typically write some subroutines in the machine's language to emulate a hardware stack. Reading and writing to the stack proceeds as follows: before an item is read from the stack, the stack pointer is decremented to point to the previous item in the stack memory. This then, is the item read from the stack; After an item is written into stack memory, the stack pointer is incremented to point to the next item in the stack. Thus, the operation of the stack can be thought of - 22 - Small C Interpreter Programmer's Manual as a stack of pancakes - numbers are piled onto the stack for temporary storage, then removed from the top as needed. In general, the C language depends very heavily on the stack. Local variables, including function arguments, are piled onto the stack when a function begins, and then removed and discarded when it terminates. As a C statement is executed, the components of the statement (constants, variables, etc.) are "pushed" onto the stack until they are needed. Then, when the statement is evaluated, the components are "poped" off the stack. Most compilers take advantage of the machine's built-in stack (if the CPU happens to have one, as most do), so access to the stack is very efficient. Still, this has become a major point of criticism by opponents of the C language. 8.4.2. Program and Data Segments Global data variables are usually stored in the same section of memory as program code; most 8 and 16 bit CPU's do not provide seperate memory segments for program code and global data. Some minicomputers and most mainframes do provide seperate program code and data memory areas. The machine then limits access to these segments by disabling the program from storing data in the code segment and possibly causing the program to go berserk. Also, the program is limited to accessing only its own global data area and attempts to read or write data outside of this global data segment is a violation. Alas, a microcomputer's operating system is at the mercy of the currently executing program and a careless program has the ability to corrupt the operating system and bring the computer to its knees. - 23 - Small C Interpreter Programmer's Manual 9. Constants You already know about decimal integer constants because we have been using them throughout this tutorial. The C language also allows you to represent numbers in hexadecimal, octal and ASCII. 9.1. Hexadecimal Constants Hexadecimal numbers are distinguished from other number representations and variables by preceding them with a "0x" (zero-"ex"), for example: 0x0 0x1b 0xfa70 are all valid hexadecimal number representations. You may also use an upper case "x" if you desire. 9.2. Octal Constants Octal numbers are distinguished by preceding them with a zero. These are all valid octal numbers: 00 033 0175160 9.3. ASCII Character Constants The numeric value of ASCII characters can be represented by surrounding the ASCII character in apostrophes, like this: A 'A' - is equivalent to decimal 65 ' ' - is a space and is equivalent to decimal 32 - 24 - Small C Interpreter Programmer's Manual Certain non-printing ASCII characters can also be conveniently represented as character constants. By preceeding certain lower case letters with a backslash character ("\"), the two-character combination can be used to represent a single one byte value. One of these you already know as the "newline" character, '\n'. Here is a complete list of these: b '\b' - "backspace", equivalent to decimal 8. r '\r' - "return", equivalent to 13. n '\n' - "newline", equivalent to 10. f '\f' - "formfeed", equivalent to 12. t '\t' - "tab", equivalent to 9. In addition, you can represent any ASCII character as a character constant using its octal equivalent preceded by a backslash. The only restriction here is that the octal representation must be exactly 3 octal digits. For example: 033 '\033' - is an ASCII "escape" character equivalent to 27. 101 '\101' - is an ASCII "A", equivalent to 'A', equivalent to 65. 377 '\377' - is not really a valid ASCII character, but it is equivalent to 255. and so on - you get the idea. 9.4. String Constants Finally, another type of constant you have already been using, is the "string" constant - a bunch of ASCII characters surrounded by quotes, for example: "this is a string\n" A string always ends with a zero byte, thus the amount of memory a string takes up is equal to the number of - 25 - Small C Interpreter Programmer's Manual characters you can count in the string plus one. In the example above, the string requires 18 bytes of storage (realize that the "\n" sequence is a single character - the "newline"!). String constants have an interesting numeric equivalent - it is an address in the computer's memory where the ASCII characters in the string can be found by functions that are equiped to deal with them. For instance, the Library Function "puts" expects its parameter to be an address in memory where ASCII character can be found and sequentially printed out to the console screen. If you tried to find out a string constant's numeric value from the shell by typing: > "hello?" -5537 > "another string..." -5537 > "what the?" -5537 > you would be surprised to find that they all have the same address - how could this be? Actually, all the string constants in the above examples do have the same address. Recall that the shell reads a line of input from the console and hands it off to the interpreter for evaluation. Since the strings all get read into the same line buffer by the shell, they all have the same address, namely the shell's input line buffer. We will discuss strings in more detail in the section on arrays and pointers. - 26 - Small C Interpreter Programmer's Manual 10. Assignment Operator In C, we assign values to variables using the "assignment" operator, "=". Do not confuse the assignment operator (a single equal sign) with the "is equal to" relational operator (two consecutive equal signs), which we will discuss later. Although C will allow you to do this under certain conditions, you will get unexpected results. The expression: a = (b + 1) * 2; is read as: take the results of the calculation of (b + 1) * 2 and assign it to the variable "a". Note that there may be only one variable to the left of the equal sign. You can if you like, string several of these assignments together like this: a = flg = x = (b + 1) * 2; Note that even here there is always only one variable to the left of each equal sign. This statement is evaluated like so: take the results of the calculation of (b + 1) * 2 and assign it to the variable "x", then assign the same number to the variable "flg", and then to "a". This implies that the assignment operator is evaluated from _____ __ ____ right-to-left, instead of the usual left-to-right. In fact it is the only binary operator supported by SCI that exhibits this peculiar behavior. This feature is most useful when initializing several variables, like so: lettercnt = digitcnt = punctcnt = 0; which would set all of the variables to zero. The assignment operator has the lowest precedence (it is performed last in an expression) of all the C operators, except for the "comma" operator (see below). 10.1. Lvalues and Rvalues It should be intuitively obvious that any attempt to store a value in what we know as a C constant is illegal. - 27 - Small C Interpreter Programmer's Manual In other words, you would never attempt to say, store the number 3 in place of the number 5: 5 = 3; The same holds true for string constants; you may not store another string in an existing string constant: "hello" = "world\n"; These types of data (constants) are collectively known as "rvalues" (pronounced "are-values"). The term rvalue stems from the fact that they may only be used on the right-hand-side of an assignment operator. On the other hand, variables do allow numbers to be stored and retrieved from them. This category of data is known as "lvalues" (pronounced "ell-values") because they may be used on the left-hand-side of an eual sign. We will encounter lvalues and rvalues again in a later discussion. - 28 - Small C Interpreter Programmer's Manual 11. Comma Operator In C the punctuation character "," (comma) is considered to be an operator, although it does nothing more except insure that sub-expressions within a statement will be evaluated in order from left to right. This operator has the lowest priority of all. It is useful for when you want to do more than one thing in a statement, like the following: ++a, b=12, c=b+a; Of course, we could also have written the above statement as: { ++a; b=12; c=b+a; } but this would not have been as concise as the first form. Commas are also used to seperate variable names in a data declaration as you have already seen, and to seperate arguments in function calls. NOTE NOTE: SCI does not support the use of the comma operator anywhere outside the context of variable seperators or function call argument seperators, as in the first example above. Any attempt to do so will result in a "syntax error" message from the interpreter. - 29 - Small C Interpreter Programmer's Manual 12. Flow Control The previous sections have dealt only with data elements (variables and constants) and with evaluating arithmetic combinations of these. C would be a poor language indeed if it only allowed a programmer to evaluate a sequential list of arithmetic expressions without giving him the opportunity to act on the results of these calculations. This section will introduce you to C's program control structures, also known as "flow control" structures. Most of these have constructs that should be familiar to all you BASIC hackers: the conditional ("if-else"), looping ("while" and "for") and program control switching ("switch"). 12.1. if and if-else The most fundamental of the flow control constructs is the "if". This allows you to perform a statement (or group of statements if we talk about a compound statement) "if" the given condition is true. In C, a condition is considered to be true when the value of an expression is non-zero, that is either a positive or negative number. It follows then, that an expression that evaluates to zero is considered to be a false condition. We write an "if" conditional in C like this: if ( <expression> ) <statement> We will be using the angle brackets (<>) to represent familiar C concepts so that you will be able to more easily identify the relavent components: here "<expression>" is any valid C expression, like "var-5" or "x + 10"; and "<statement>" may be either a simple or compound statement - but, more about statements later. The relavent components in the "if" statement are: obviously the "if" word which identifies this flow control construct; a left parenthesis followed by an expression followed by a right parenthesis; then a C statement. Now a few words about syntactics: 1) The "if" must be in lower case letters, most C compilers will usually not accept "If", or "IF" or "iF" (and neither will SCI!). - 30 - Small C Interpreter Programmer's Manual 2) The matched left and right parentheses must be included, and SCI requires that the "if", the left parenthesis, the <expression> and the right parenthesis appear on the same line in the program. 3) The <statement> may be either a simple statement or a compound statement. NOTE NOTE: SCI requires that the "if" and the parentheses appear on the same line in your program text, but the <statement> may appear on the following line. This is only a restriction of the SCI interpreter - the standard C language lets you put as much horizontal and vertical "distance" between elements of an "if" statement as you like. The "if" flow control construct behaves as follows: 1) The <expression> is evaluated. 2) If the result of <expression> is true (a non-zero value) then the <statement> is executed. 3) If the result is false (zero) the <statement> is skipped and program control passes to the next statement. For example: if ( 2 + 2 ) a = 5; would always set the variable "a" to 5 because the <expression>, which evaluates to 4 in this case, is always non-zero. And the <statement> in this example: if ( 0 ) a = 5; would never be reached because the <expression> is always false. As a last example, look at this: - 31 - Small C Interpreter Programmer's Manual if ( a = b + c ) b = b + 1; Here the value of the <expression> depends on the results of the addition of "b" and "c", which we have no way of knowing just by looking at the example out of context. As a side-effect, the result of the addition is stored in the variable "a". It is very important that you realize that the equal sign in "a = b + c" is not making a comparison between the value of "a" and "b + c", as you might assume if you were looking at a similar statement in BASIC. In other ___ words, we are not saying "if a is equal to the sum of b and c". 12.1.1. More About Statements Earlier we promised to tell you more about the concept of C statements. A statement, as you already know, can be either an expression such as "a = 5 + 5" followed by a semicolon (don't forget the semicolon!) or it may be a group of these simple statements surrounded by left and right curly braces, like this: { a = b + c; b = b + 1; } or this: { a = b + c; b = b + 1; } or a compound statement within a compound statement as in this example: { { a = b; b = 1; } a = b + c; b = b + 1; } We now expand our definition of a C statement to include the "if" and later all of the other flow control constructs as well. In other words, the template for an - 32 - Small C Interpreter Programmer's Manual "if" we showed you before: if ( <expression> ) <statment> can be thought of as a single unit and used wherever a <statement> is used. Now we can write multiple "nested if's" like this: if ( a + 5 ) if ( b - 1 ) c = 0; which would be "read" by the computer as follows: 1) if "a + 5" is true (non-zero) then go to step 2 otherwise go to step 3. 2) if "b - 1" is true, then assign 0 to "c". 3) go on to the next statement in the program. The "if" statement also has an optional "else" clause, which looks like this: if ( <expression> ) <statement> else <statement> Notice that the "else" keyword must be in lower case letters also. Again, the first <statement>, the "else", and the second <statement> may be on seperate lines of program text or they may all be on the same line. The "if-else" statement, as it is called, is read as follows: 1) if the <expression> is true, then execute the first <statement> and then go to step 3. 2) else, execute the second <statement> and then go to step 3. 3) go on to the next statement in the program. The C language allows you to nest "if-else" statements as deeply as you wish, for example: - 33 - Small C Interpreter Programmer's Manual if ( a + 3 ) if ( b + 5 ) if ( c + 7 ) d = 0; else d = 1; else d = 2; else d = 3; It should be obvious from the way the statements were indented how each "else" matches its "if". As a matter of definition, an "else" clause matches the nearest preceding "if" clause. If there are more "else's" than "if's" in a program, then this is an error condition and you will be warned by SCI. If you are ever unsure how nested "if-else" combinations will match up, you can always use curly braces to bind them together the way you want: if ( a + 3 ) { if ( b + 5 ) { if ( c + 7 ) d = 0; else d = 1; } else { d = 2; } } else { d = 3; } You can also use another "if-else" statement in the "else" clause of a preceding "if-else", for example: - 34 - Small C Interpreter Programmer's Manual if ( a + 3 ) d = 1; else { if ( a + 4 ) d = 2; else { if ( a + 5 ) d = 3; else d = 4; } } Because it is a matter of personal style, there are no hard and fast rules to follow when indenting program statements like this. However, the above example is more commonly indented like this: if ( a + 3 ) d = 1; else if ( a + 4 ) d = 2; else if ( a + 5 ) d = 3; else d = 4; This saves you from running off the right edge of the screen when writing very deeply nested "if-else's" and it looks very much like a multi-path switch (an "ON GOTO" statement in BASIC). 12.1.2. Relational Operators Sometimes it is necessary to change the program flow depending on whether a variable is equal to a certain value. The C language has this ability to test equality of two expressions using a set of operators (similar to the addition, multiplication, assignment, etc.) known as the "relational operators". If we wanted to know if a variable were equal to a certain value, for instance we could say: a == 5 - 35 - Small C Interpreter Programmer's Manual The "==" (which is read as: "is equal to") operator compares the two items to the left and right of it and leaves a value of one if they are equal, zero if they are unequal. So the value of this expression would be one if "a" is equal to 5 and zero otherwise. Thus, the statement: if ( a == 5 ) b = 0; would set "b" to zero only if "a" equals 5. We promised you a set of these operators, so here they are: ________ ____ __ operator: read as: == is equal to != is not equal to < is less than > is greater than <= is less than or equal to >= is greater than or equal to Notice that there may be no spaces between the two equal signs (=) in the "is equal to" operator nor between the exclamation point (!) and the equal in the "is not equal to". If there is a space between them, they will be assumed to be two seperate operators and you will get a "syntax error" message from SCI. Needless to say, the same goes for the <= and >=. 12.1.3. Logical Operators The C language also allows you to combine groups of relational expressions with "and" and "or" clauses. For example, given two sets of conditions you can determine if both are true, or if at least one is true. These "and" and "or" clauses are known as the "logical operators" in C: ________ ____ __ operator: read as: && and || or - 36 - Small C Interpreter Programmer's Manual Notice that there may be no spaces between the two ampersands (&) and vertical bars (|). The expression: a==5 && b==3 ___ will be true only if "a" is equal to 5 and "b" is equal to 3. a<0 || 10<a In this example the expression is true if "a" is less __ than 0 or greater than 10 (do you see that 10<a and a>10 are identical?). One final note about the logical operators: standard C stops evaluating an expression that contains logical operators after the truth or falsehood of the expression is known. For example: a==b && c==d Assume that "a" is not equal to "b". Standard C would not even bother checking the relation "c==d" because the "and" clause requires both expressions to the left and right of the "&&" to be true - if one of the components is false, the entire expression is false. So, since the first component encountered ("a==b") was found to be false, the truth or falsehood of the entire expression is already known and there is no need to evaluate "c==d". NOTE NOTE: SCI is not as smart as a standard C compiler and blindly evaluates every sub-expression in a logical expression. This can lead to some very hard to find errors if for example you alter a variable in one of the subexpressions of a logical operation - sorry folks! 12.1.4. Precedence and Associativity You can combine as many "and" and "or" clauses as - 37 - Small C Interpreter Programmer's Manual necessary: a==5 || b==3 && c==4 This expression will be true under one of two conditions: 1) b is equal to 3 AND c is equal to 4, or 2) a is equal to 5. This example shows a very important property of logical operators that we have already encountered in the discussion of the arithmetic operators (+, -, *, etc.), namely precedence. In C, the && operator takes precedence (is performed before) the || operator. As with the arithmetic operators the logical operators are performed from left to right. So, if we have more than one operator of the same precedence in an expression: a==5 && b==5 && c==5 we know that C performs the tests for equality from left to right. Although we haven't come right out and said it before, it should be obvious from the examples that the relational operators have higher precedence than the logical operators. Specifically, >, >=, < and <= have higher precedence than == and != which have higher precedence than && which has a higher precedence than ||. Please refer to the Language Summary section of the User's Manual for a complete list of C operators and their order of precedence. Furthermore, relational operators associate from left to right, although it is hardly ever necessary to use more than one consecutive relational: a == 5 != 1 Notice in this example that "a == 5" is performed first which would result in either a zero or a one. Examine the following expression closely: a < 5 == b < 5 ____ This expresion will be true if "a" and "b" are both ____ ____ _ ____ _____ __ __ _______ ____ less than 5 or "a" and "b" are both equal to or greater than - 38 - Small C Interpreter Programmer's Manual _ 5. As always, whenever you are in doubt about the associativity or precedence of operators, either use parentheses to bind operands and operators together, or consult the table of operators in the User's Manual. 12.1.5. Examples Finally armed with these new facts about C, we are ready to try some practical examples using the SCI interpreter. Enter the following program using the SCI editor: convert(n) { char c; puts("to decimal (d), hex (x) or octal (o) ?"); c=getchar(); if(c=='d') putd(n); else if(c=='x') putx(n); else if(c=='o') puto(n); else puts("what?\n"); } As you can probably tell, this is a number conversion routine. It asks the operator whether to convert the number passed to it ("n") to decimal, hexadecimal or octal. Now at the shell prompt, type: > convert( 255 ) to decimal (d), hex (x) or octal (o) ?x 0xff 0 > If your screen did not look like the above, there is something wrong - fix it up and try again. Now modify the program to accept either lower or upper case d's, x's and o's (hint: use the || operator). - 39 - Small C Interpreter Programmer's Manual 12.2. while One of the things that makes a computer such a powerful tool is its tireless ability to perform repetitive tasks. This is why every programming language has some sort of "looping" flow control. The C language offers three types of loop constucts: the "while", "for" and "do-while". This version of SCI only supports the "while" and "for". The "while" flow control looks something like this: while ( <expression> ) <statement> Notice that its structure is very similar to the "if" construct and all of the syntactical rules apply as well. This statement is executed as follows: 1) evaluate <expression> and if it is false, go to step 4. 2) execute <statement>. 3) go to step 1 4) go on to the next statement in the program. As with the "if" statement, <expression> is considered to be true if it evaluates to non-zero, and false if it is zero. Let's look at an example: loop() { int a; a = 10; while ( a > 0 ) { putd( a ); a = a - 1; } puts("all done\n"); } This loop will get executed exactly 10 times - each time the variable "a" is decremented by one until it equals - 40 - Small C Interpreter Programmer's Manual zero. When "a" reaches zero, the expression "a > 0" will become false and program execution will continue with the next statement in the program. There is also a more direct method of breaking out of a "while" loop without having to wait until control returns back to the <expression> evaluation and testing. Using a "break" statement, you can directly jump out of a "while" and continue with the next statement in the program. The following demonstrates the use of a "break": loop() { int i, r; i = 13560; putd( i ); while ( 1 ) { r = i / 10; if ( r == 0 ) break; putd( r ); i = r; } puts("all done\n"); } Since the <expression> is always true (1 is always non-zero), this loop would be repeated until the cows came home. The "if" statement within the loop will break out of the loop when the remainder of the division results in zero. We leave as an exercise for the student to figure out what this little program does. 12.3. for The "for" looping construct is similar to the "while". Its format is as follows: for ( <expression> ; <expression> ; <expression> ) <statement> The syntactical requirements of the "for" construct are similiar to those of the "while" - the "for" and the parentheses and everything between them must be on the same program line. Also, the three <expression>'s inside the - 41 - Small C Interpreter Programmer's Manual parentheses must be seperated from each other by two semicolons as shown. Actually, the "for" is simply a method of clearly presenting to the reader the most commonly needed elements relavent to a program loop: an "initialization" part, a "loop test" part and an "iteration" part. These three elements are clearly identifyable, and correspond to (reading from left to right) the three <expressions> within the parentheses. A "for" statement would be executed as follows: 1) evaluate the first <expression>, disregard the result. 2) evaluate the second <expression> and if it is false, go to step 5. 3) execute <statement>. 4) evaluate the third <expression> and go to step 2. 5) go on to the next statement in the program. We could have written the first example given for the "while" using a "for" statement: loop() { int a; for ( a = 10; a > 0; a = a - 1 ) putd( a ); } The "break" statement may also be used to break out of a "for" loop. One last interesting feature of the "for" is that any or all of the three <expressions> may be missing. If the second <expression> is missing, the "loop test" will always evaluate to true. Thus, the second example of the "while" loop above could have been written: - 42 - Small C Interpreter Programmer's Manual loop() { int i, r; for ( putd( i = 13560 ); ; i = r ) { r = i / 10; if ( r == 0 ) break; putd( r ); } } Here, the three <expressions> are: putd( i = 12560 ) missing! i = r And the most efficient way of writing a "forever" loop is: for ( ;; ) puts( "hello, world\n" ); 12.4. switch The last and most complex flow control we will examine is the multi-path "switch" statement. The "switch" is similar to BASIC's "ON GOTO" statement. Here is the template of a "switch" statement: - 43 - Small C Interpreter Programmer's Manual switch ( <expression> ) { case <constant expression> : <statement> case <constant expression> : <statement> . . . case <constant expression> : <statement> default : <statement> } Again, the word "switch", the left parenthesis, the <expression> and the right parenthesis must be on the same program source line. The matching left and right curly brace at the beginning and end of the switch are not actually required but are necessary as you will soon see. The words "case" and "default" are only meaningful within the context of a "switch" statement. There may be any number of "case <constant expression> :" sequences but only one "default :". The <constant expression>'s are simply <expression>'s that contain only constants (no variables!). So, the following would all be examples of <constant expression>'s: 2 + 2 25 * (365 / 7) 37/12 > 10 NOTE NOTE: Standard C requires that only <constant expression>'s follow a "case", however SCI allows you to use any valid <expression> as an added bonus. Keep this fact in mind when writing programs that will eventually be transported to standard C! The "switch" statement behaves as follows: 1) evaluate the <expression>. 2) compare the results of <expression> to each of the <constant expression>'s after the "case's" sequentially from top to bottom. 3) if the value of <expression> matches one of the - 44 - Small C Interpreter Programmer's Manual <constant expression>'s, continue program execution with the statement immediately following the colon. All other "case" and <constant expressions> are ignored. 4) if none of the <constant expression>'s match <expression>, jump to the <statement> immediately following the word "default" 5) if a "break" statement is encountered, jump to the end of the "switch" statement (the <statement> immediately following the }). Although this seems complicated at first, a "switch" is really just a multi-way program jump. It allows you to jump to anywhere within a statement, based on the value of an expression. Here's an example of a switch: convert(n) { char c; puts("to decimal (d), hex (x) or octal (o) ?"); switch ( getchar() ) { case 'd': putd(n); break; case 'x': putx(n); break; case 'o': puto(n); break; default: puts("what?\n"); } } NOTE NOTE: Standard C allows you to place the "default" word anywhere within the "switch", and program control will jump there only after all of the "case <constant expression> :"'s have been checked and no match found. Here again, SCI dares to be - 45 - Small C Interpreter Programmer's Manual different! If a "default" is encountered before a matching "case", the program continues with the <statement> following the "default". Therefore, it is a good idea to always place your "default" statements at the end of the "switch". - 46 - Small C Interpreter Programmer's Manual 13. Arrays An array in C is a block of contiguous memory locations (meaning they are located "one after the other" in memory) that all have the same type ("char" or "int") and can be accessed individually. These individual data items in an array are known as the array's "elements". You have already used arrays earlier, in your very first C program, namely the sequence of ASCII characters in the string "hello, world\n". The array's elements are the ASCII characters 'h', 'e', 'l', etc. This array however, could not be used to store any information other than that sequence of characters, just like the integer constant 5 let's say, can not be used to store a different number. In this section we will show you how to create and use arrays for data storage and retrieval. Arrays are declared in a similar fashion as simple variables, but following the array's name you must indicate how many elements the array will have. The size of an array is constant, once it has been declared it can not be changed. Below is an example of an array declaration char vartable[15], macnam[100]; This statement declares two arrays that have 15 and 100 elements respectively. The square brackets ([ and ]) identifies the variable as being an array, they are also required when you wish to access one of the array's elements: c = vartable[ 5 ]; In C, array elements are counted from zero instead of _____ one, so the above statement takes the sixth element of "vartable" and stores it in the variable "c". To access the _____ first element of the array, we would write: vartable[0] = 35; ____ Consequently, the last element of the array would be ___ "vartable[14]" and not "vartable[15]". In fact, if you did attempt to store a number in "vartable[15]", you would overwrite some unknown location in memory that was already being used as storage for another variable or, worse yet, that was part of your program code. The results of - 47 - Small C Interpreter Programmer's Manual overrunning a C array like this are unpredictable and are dependent on the environment the C program is running in (the type of machine, the C compiler used, etc.) When the name of an array is used by itself without the square brackets as in: i = vartable + 5; it is taken to be a pointer to the first element of the array. In the example above, "i" would be assigned the ______ ________ ___ memory location of the sixth element in the array, and not ___ _____ the value of this memory location. The Library Function "gets()" reads a line of input from the console keyboard and places the characters at the address pointed to by its argument. This function waits for the user to hit a carriage return before it returns to the caller. The input line is always terminated with a zero byte by "gets()" and the carriage return is stripped out. This makes it suitable for printing by its partner, "puts()". Try the following program: greet() { char name[ 80 ]; puts("hello, what's your name? "); gets( name ); puts("nice to meet you, "); puts( name ); puts(". Have a nice day!\n"); } - 48 - Small C Interpreter Programmer's Manual 14. Pointers The last example above leads us directly into our next discussion. In C, you have the ability to access a memory location by "pointing" at it with a variable. This type of variable is known as a "pointer" in C. NOTE NOTE: The number of bytes of storage a pointer variable needs depends on the environment the C program is running in. All 8-bit personal computers (8080, z80, 6502, etc.) use 2 bytes for pointer variables. The IBM-PC which has an 8088 CPU may use either 2 or 4 bytes for pointer variables, depending on the C compiler used. SCI always uses 2 bytes. C knows about the type of variable being pointed at from the pointer's declaration: char *char_pointer; int *int_pointer; Above we declared two variables, "char_pointer" and "int_pointer". The asterisk (*) in the declaration statement identifies the variables as being pointers. the "char" and "int" keywords define the type of variable that the pointer points to. To illustrate: i = *int_pointer; _______ This would retrieve the integer (two bytes in SCI) ________ found at the memory location addressed by the contents of "int_pointer", and store it in "i". In this example, we can't tell what will be stored in "i" because we don't know what the contents of "int_pointer" is. Recall from an earlier discussion that SCI always initializes its variables to zero so in this case, "i" would contain the two bytes found in memory locations zero and one Unless you know what is in memory locations zero and one, this information is not very useful. The power of pointers lies in the fact that they can be made to point at an array, like this: - 49 - Small C Interpreter Programmer's Manual char vartable[15], *cp; cp = vartable; c = *cp; cp = cp+1; d = *cp; cp = cp+1; e = *cp; Here we have set the character pointer "cp" to point at the first element of the array "vartable", and assigned the ________ contents of this first element to the variable "c" just by letting "cp" point at it. By simply adding one to "cp" we have made it to point at the next element in "vartable". 14.1. Lvalues and Rvalues Revisited Pointers are useful because they can be changed (bent?) to address any location in memory whereas arrays are fixed and always point to their first element. For example, if your tried to do this: char a[10]; a = a + 1; ____ you would get an error message. The C language does ___ _____ ___ __ ______ ___ _____ __ __ _____ ________ not allow you to change the value of an array variable. If it did there might be the possibility of your program "forgetting" where the data in the array is located. Thus arrays can be put in the same category as strings and integer constants, namely "rvalues" (see an earlier discussion on Lvalues and Rvalues). The attempt to change the array variable "a" in the example above would therefore reward you with a "need an lvalue" error message from the SCI interpreter. Pointers on the other hand are more analagous to variables - they can be modified and are therefore considered to be "lvalues". 14.2. Pointer Operator The asterisk in the examples above is known as the - 50 - Small C Interpreter Programmer's Manual "pointer" operator. This is a unary operator and is used in the same manner as the negation (-) unary operator. The pointer operation tells C to treat its associated pointer variable as a memory address and to store or retrieve the _______ data item at that address. Note that the operand of a pointer operator must have been declared as a pointer, or C will complain. This is in your own best interest because we humans tend to forget little details like this. For example, if you wrote: char c, d; d = *c; you would get a "not a pointer" error message from SCI. Now, try typing in this little program using the SCI editor: prints(s) char *s; { while(*s) { putchar(*s); s=s+1; } } The Library Function "putchar()" accepts a single argument and prints the ASCII representation of this argument to the console screen. This program takes a pointer to a character string as an argument. Then, while the character being pointed at is non-zero, "putchar()" prints the character onto the console. The pointer is then incremented (s=s+1) so that it points at the next character in the string. Now execute the following command from the shell: > prints("hello, world\n"); This should have resulted in the words "hello, world" printed on the console. Except for the fact that pointers may be changed and arrays may not, C treats both of them identically. For - 51 - Small C Interpreter Programmer's Manual example if we have the following two data declarations: char c, ca[ 10 ]; char *cp; we can choose to view the array variable "ca" as a pointer, and the pointer variable "cp" as an array in our programs, like so: c = *ca; cp[ 5 ] = c; So, we could have written the sample program from before like this: prints(s) char *s; { int i; for ( i=0; s[i]; i=i+1 ) putchar( s[i] ); } This would have left the pointer argument "s" unaltered when the "for" loop was finished. This is sometimes necessary, as in the following example: prints10(s) char *s; { int i, j; for ( j=0; j<10; j=j+1 ) { for ( i=0; s[i]; i=i+1 ) putchar( s[i] ); } } Here the string passed to "prints10()" is printed on the console ten times. If we had incremented the character pointer "s" instead of using the index "i", then the second time through the outer loop would have started with "s" pointing to the character after the end of the string. - 52 - Small C Interpreter Programmer's Manual 14.2.1. Pointer Expressions We stated that C knows the type of data item a pointer is pointing to ("char" or "int"). Being a rather dumb (and therefore compact) interpreter, SCI does not know what type of data item is being pointed at when the pointer is hidden in an expression somewhere, like so: i = *(ip + 5); In this example we are trying to retrieve the data item pointed at by "ip" and offset by 5. If "ip" was a pointer to an "int", we would think that we are retrieving the sixth 2-byte integer of the array pointed at by "ip". Physically, we are interested in the tenth and eleventh bytes in the array. The above expression, however, will retrieve only one byte for us (the sixth byte in the array) instead of two, and from the wrong place in the array. This is a limitation only of SCI - most C compilers are smart enough to know better and the above statement would have retrieved the sixth "int" from the array, as expected. On occasion you may wish to use integer constants as pointers, like this: char c; c = *0x0100; When a constant is used as the target of a pointer operation, SCI will access the two bytes (an "int") at the location specified by the value of the constant, in this case at location 100 hex. You can get as creative as you want when using constants as pointers: char c, offs; c = *((0x101 + offs) * 2); Note that SCI will allow you to use variables that have not been declared as pointers in pointer expressions if they are enclosed in parentheses as shown above. - 53 - Small C Interpreter Programmer's Manual NOTE NOTE: Standard C does not allow you to use constant expressions as pointers, any attempt to do so will usually result in an error message. 14.2.2. printf() C functions do not intrinsically know whether their arguments are printable strings or just an array or numbers, like BASIC does. Therefore there are no C functions that are analogous to BASIC's PRINT statement which prints either a number or a string depending on its argument. The standard C Library Function "printf()", however, performs a print operation similar to BASIC's PRINT statement. "Printf", which is read as "print-eff", stands for "print formatted". It is the most unusual standard C function because it accepts a variable number of arguments, depending on the contents of its first argument. The first argument to "printf" is a string of characters and is known as the "control string". "Printf" works like this: it scans through the characters in the control string and prints them out on the console screen; if a percent symbol (%) is encountered in the control string, the character following ________ the "%" determines how printf's next argument will be processed. For example, if the character following the "%" is a lower case letter "s", the next argument is assumed to be a character string and is printed out to the console instead of the "%s" character combination. A "%d" combination in the control string takes its next argument to be an integer and prints its decimal value. "Printf" keeps track of which arguments have already been printed by a "%-letter" combination, so that the next "%-letter" combination affects the next argument in the argument list. For example, try the following command from the shell: printf("%s, did you know %d * %d is %d?\n","Bob",376,49,376*49) The "%s" conversion treats the second argument, "Bob" as a string (which it is!) and prints it; the first "%d" grabs the next argument in the list (376) and prints it as a decimal number; the second "%d" prints 49 as a decimal number; finally, the third "%d" takes the product of 376 and 49 and prints it as a decimal number. What should have appeared on your screen is: Bob, did you know 376 * 49 is 18424? - 54 - Small C Interpreter Programmer's Manual "Printf" also recognizes these other conversion codes: x %x - prints its argument as a hexadecimal number. The characters "0x" do not appear in the printed number - you must add them if needed, like so: printf( "%d = 0x%x\n", 376, 376 ) o %o - prints its argument as an octal number. c %c - prints its argument as an ASCII character. 14.3. Address Operator In an earlier discussion about the scope of variables, we said when a variable is passed to a function, the called function creates a clone of the caller's variable and copies its contents into this local variable. This way the function can not alter the contents of the caller's variable. How then can we have a function alter the contents of our local variables if it becomes necessary? There are several options open to us: 1) write the function so that it returns a value which we can then assign to our local variable, 2) have the function put the value into a global variable which we can access, or 3) pass the function the address of our local variable. The first option only allows the function to pass back one piece of information, thus limiting its usefulness. Option 2 is an acceptable method but forces the function to become more dependent upon the entire program structure. This is fine for application-specific functions, but severly restricts the modularity of general purpose functions. The accepted method is to pass the function the address of our variable using the "address operator", "&", like so: - 55 - Small C Interpreter Programmer's Manual prog() { char c; func( &c ); # call "func()", pass the address of "c" } func( ptr ) char *ptr; { *ptr = 12; } The ampersand (&) as used above is a unary operator _______ that tells C we want to use the address of the associated ________ __ _____ _____ ___ variable instead of its contents. In other words, the _______ ________ ______ _ _______ address operator yields a pointer to its associated operand. That's why we declared the argument to the function "func()" as a pointer to a "char". In the above example then, the local variable "c" in "prog()" would have been set to 12 after the call to "func()". Extreme caution must be exercised when passing pointers to variables like this. If we had instead declared "ptr" as a pointer to an "int" (int *ptr;) in the function, "func()", then the assignment "*ptr = 12;" would have destroyed the memory location following "c" and possibly caused the program to crash. Note that you may only use the address operator on lvalues; this means only simple variables and pointers. If you try to use the address operator on a constant, a string or an array you will evoke a "need an lvalue" error from SCI. Now enter and test this little program from the SCI interpreter: - 56 - Small C Interpreter Programmer's Manual words() { char *word, *cp, linebuf[80]; puts("type some words: "); gets(cp = linebuf); while(cp) { cp = parse(cp, &word); puts("word = <"); puts(word); puts(">\n"); } } parse(str,word) char *str; int *word; { while(*str==' ') ++str; *word=str; while(*str!=' ' && *str) ++str; if(*str==0) return 0; *str=0; return str+1; } and from the shell execute the function "words()". What does this program do? 14.3.1. scanf() The companion to the Library Function "printf()" is "scanf()" (read "scan-eff"). This function performs the reverse operation of "printf()", that is, it converts strings and numbers read from the console keyboard and places them into program variables. This means that its ________ arguments must be pointers to the appropriate data type. Examine the following program: - 57 - Small C Interpreter Programmer's Manual getname() { char firstname[20], lastname[20]; int zip; puts("What is your first, last name and zipcode?"); scanf("%s %s %d", firstname, lastname, &zip ); printf("firstname = %s\n",firstname); printf("lastname = %s\n",lastname); printf("zipcode = %d\n",zip); } Scanf assumes that a string is a stream of consecutive non-blank characters. The function will not stop reading input until all of its conversion (%-letter) codes have been satisfied, or until an end of input (control-Z in MS-DOS) is __ ___ encountered. This means that carriage returns do not cause scanf to quit reading and return to the caller. Carriage returns are simply treated as spaces and tabs, collectively known as "white space". In the program above, you could have entered you first and last name on seperate lines if you like, or on the same line seperated by one or more spaces or tabs. _______ Notice that the address of the integer variable "zip" was passed to scanf; do you now understand why? If we had used the following statement instead: scanf( "%d", zip ); ________ then the contents of "zip" would have been used as the location where scanf would place an integer value. If the contents of "zip" had been zero, then memory locations zero and one would have been altered by scanf, and would have possibly damaged the operating system. - 58 - Small C Interpreter Programmer's Manual 15. Increment and Decrement Operators As we have already seen, we can use several methods to access elements in an array. Let's say we had an array and wanted to access its elements sequentially, one after the other. We could either declare a pointer to the array and then increment the pointer by one; or we could declare an integer variable to be used as an array index and increment it each time by one, like so: char a[10], *p; int i; # set all 10 elements in the array "a" to zero, # using a pointer: p=a; i=0; while(i<10) { *p = 0; p=p+1; i=i+1; } # ...and using an index: i=0; while(i<10) { a[i] = 0; i=i+1; } Since these operations comes up often in programming, the C language offers a very efficient method of incrementing and decrementing varibles. These are appropriately enough, called the "increment" and "decrement" operators, "++" and "--". The increment/decrement operators are unary operators and can appear either before or after a variable name, like this: int i; ++i; # increment "i" by one i++; # same thing --i; # decrement "i" by one i--; # and again ______ If the operator appears before the variable, it is known as _____ a "pre-" increment or decrement; if it appears after the - 59 - Small C Interpreter Programmer's Manual variable, it is a "post-" increment/decrement. The ______ pre-inc/dec operators perform their function before the variable is used in the expression, whereas the post-inc/dec _____ operators perform their function after the variable has been used in the expression. This is best explained with an example: incdec() { int i; i = 0; putd( ++i ); i = 0; putd( i++ ); } The first instance of "putd()" would print a 1 - the variable "i" was increment by one before its value was passed to "putd()". Now we set "i" to zero again and the second call to "putd()" will print a 0. This is because the post-increment operator passes the value of "i" to the ______ function "putd()" before it gets incremented by one. These operators are very handy for quickly scanning through an array like this: prints(s) char *s; { while ( *s ) putchar( *s++ ); } When using the increment/decrement operators on pointers, SCI knows what data type the pointer is referencing and adjusts the pointer so that it points to the next/previous data item. In other words, when incrementing a pointer to an integer, the pointer is incremented by 2 instead of one so that it points to the next integer. If we wanted to print out all the numbers in an integer array, we might do something like this: - 60 - Small C Interpreter Programmer's Manual dump() { int array[ 10 ], *ap; ap = array; for ( i=0; i<10; ++i ) printf( "%d\n", *ap++ ); } - 61 - Small C Interpreter Programmer's Manual 16. A Tour Through the File I/O Functions The formal definition of the C language does not really include any of the Library Functions we have discussed so far. However, most of these have become defacto standards and are considered a part of the language's support library. Although the exact usage of support functions may vary from one compiler implementation to the next, most C compilers adhere to a "standard" to some degree. This section discusses SCI's implementation of the file I/O functions which is fairly compatible with the "standards" proposed by the authors of the C language. This section only attempts to clarify some points concerning the file I/O functions and is not meant as a reference. Please refer to the section in the User's Manual titled "The Library Function" for exact details about these functions. 16.1. fopen() Before a file can be used (read from or written to), it must first be "opened" with the Library Function "fopen()". Opening a file ensures that the file exists and is readable/writable and prepares internal data structures for dealing with the file. Before a C program starts up, three "files" are opened for it by the "operating system", these are known as the "standard input", "standard output" and "standard error" file. These usually default to the user's console keyboard and screen. The "standard error" file is an output file and always defaults to the user's console screen. It is usually used by the program to display error messages. The reason we like to have two output files is because we don't want to intermix program error and informational messages with program output data, and to insure that error messages always appear on the user's console. To open a file, "fopen()" must be called with two arguments: the file name, and a character string that defines how the file is to be accessed. For example, int channel; channel = fopen( "SHELL.SCI", "r" ); would open the file "SHELL.SCI" for reading ("r"). MS-DOS - 62 - Small C Interpreter Programmer's Manual allows the file name to be in upper or lower case, other operating systems may not be so indifferent about file names. The second string, known as the "open mode", must contain either a lower case "r" to open the file for reading, "w" for writing or "a" for appending. When a file is opened for reading, it must already exist or "fopen()" will return an error code. If a file is opened for writing, it may or may not exist; if it does exist, it is first deleted before the open. If a file is opened for appending and the file exists, it is opened for writing, but data is written to the current end of the file. If the file does not exist, an open for append acts like an open for write. You may also open a file for both reading and writing, meaning you may intermix read and write functions on the same file, but see the section on the Library Functions for more information. The value returned by "fopen()" is an integer known as the "channel number" and points to the previously mentioned internal file control data structure. This channel number is then used by the other file read/write functions to access the file. If "fopen()" was unable to find the file (file opened for reading) or the file could not be created (file opened for writing), it returns a zero, indicating failure. The special channel numbers 1, 2 and 3 may be used to read and write from/to the standard input, output and error files. These channel numbers may be used with the file read/write routines at any time, unless of course you have closed these channels. 16.2. fclose() When a file is no longer needed, it should be "closed" by the program. Closing a file ensures that the file is safely stored on disk and it frees up the internal file control data structure. This function expects a single argument, the file pointer: fclose( fp ); and returns a zero if the file was closed successfully, or a -1 if an error occured (the file was never opened, disk is write protected, etc.). - 63 - Small C Interpreter Programmer's Manual 16.3. fgetc() and fputc() The functions "fgetc()" and "fputc()" are used to read and write respectively a single character from/to a file. Both of these functions advance a "file position pointer" which points to the next character to be read/written to/from the file. This file position pointer is one of the items in the aforementioned internal file control data structure. These functions are used like so: copy(fromfile,tofile) char *fromfile, *tofile; { int fromchannel, tochannel, c; fromchannel = fopen( fromfile, "r" ); tochannel = fopen( tofile, "w" ); while ( (c = fgetc( fromchannel )) != -1 ) fputc( c, tochannel ); fclose( fromchannel ); fclose( tochannel ); } This little program copies the file whose name is the string at "fromfile" to the file whose name is at "tofile". The function "fgets()" returns the character that was read from the file (a single byte value from 0 to 255) or a minus one if the end of the file was reached or if some other error occured. The function "fputc()" returns the character that was written or a minus one if an error occured. 16.4. fgets() and fputs() You may also read and write disk files a "line" at a time with the functions "fgets()" and "fputs()". A "line" is a sequence of characters in the file that end with a newline ("\n") character. These are similar to the functions "gets()" and "puts()", which read and write from/to the standard input and standard output, with the exception that the newline character is copied into the line input buffer by "fgets()" and a newline is automatically appended to every string written out to the file by "fputs()". Note that the two functions fputs("hello",2) and puts("hello") are identical. - 64 - Small C Interpreter Programmer's Manual 16.5. fread() and fwrite() Sometimes it is useful to be able to read or write a file in arbitrarily long "blocks". For example, suppose we wanted to store an array of integer numbers in a file. The character read/write functions ("fgetc()" and "fputc()") would work but would be less efficient than writing several characters at a time. The functions "fread()" and "fwrite()" are ideal for these situations: sortfile() { int array[ 100 ]; int channel; channel = fopen( "NUMBERS.DAT", "r" ); fread( array, 200, channel ); fclose( channel ); sort( array, 100 ); channel = fopen( "NUMBERS.DAT", "w" ); fwrite( array, 200, channel ); fclose( channel ); } sort(a,n) int a[], n; { int temp, i, j; for ( i=0; i<n-2; ++i ) { for ( j=i; j<n-1; ++j ) { if ( a[j] > a[j+1] ) { temp=a[j]; a[j]=a[j+1]; a[j+1]=temp; } } } } This program reads an array of 100 numbers from a file, sorts them in numeric order and writes them back to the file. Note that we asked "fread()" and "fwrite()" for 200 bytes. Since the array consists of 100 integers and each integer is 2 bytes, the array is 200 bytes long. Also, be sure to close a file when it is no longer needed. If we had neglected to close the file after the - 65 - Small C Interpreter Programmer's Manual "fopen()" for reading, the second call to "fopen()" would have altered our file pointer. The value of the first file pointer would have been destroyed and the internal file control data structure would have been lost in limbo forever. Although this wouldn't have caused any damage, it is very sloppy programming. Keep in mind that you have only 10 file control data structures available. 16.6. fseek() and ftell() All of the file read/write functions advance an invisible "file position pointer" which determines where in the file the next character will be read from or written to. Sometimes it is necessary to re-read a character or group of characters in a file, or to write over the current contents in a file with new data. The function "fseek()" can be used to relocate the file position pointer to anywhere within the file, and allow you to re-read or re-write data in the file as necessary. Ftell simply returns the current value of the file position pointer. Examine the following sample program: link() { int start, current, inchannel, outchannel, c; inchannel = fopen( "RAW.DAT", "r" ); outchannel = fopen( "LINKED.DAT", "wr" ); start = 0; fwrite( &start, 2, outchannel ); while ( (c=fgetc( inchannel )) != -1 ) { if ( fputc( c, outchannel ) == 0x00ff ) current = ftell( outchannel ); fseek( outchannel, start, 0 ); fwrite( ¤t, 2, outchannel ); fseek( outchannel, current, 0 ); start = current; } } fclose( inchannel ); fclose( outchannel ); } This program copies the file RAW.DAT to LINKED.DAT. Each time a byte of all one's (FF hexadecimal) is encountered in - 66 - Small C Interpreter Programmer's Manual RAW.DAT, the program backs up to the previous start location in LINKED.DAT (indicated in the variable "start") and inserts the file's current file position pointer ("current"). In other words, the program creates a file identical to RAW.DAT except that the data in the file contains information that tells where all of the 0xff's are located within the file - a linked list. Since SCI only supports integer variables, this limits the maximum range of absolute file positioning available with "fseek()" to 32767 from the beginning or end of the file. You can however, position the file pointer to within _______ +/-32767 bytes from the current position. This allows you to position the file pointer anywhere within the file, no matter how large the file is. Standard C uses "long" data variables instead of "int"'s for specifying the file position offset. Long's are usually twice the size of an "int" (four bytes instead of two), which gives you a much larger range of absolute file positioning. - 67 - Small C Interpreter Programmer's Manual 17. The Debuger SCI provides a powerful program debugging facility that allows you to execute your programs with complete control. When the debuger is active, it takes control of your program and allows you to step through the program in a controlled fashion. You have the option of either executing a line at a time, or stop at any line in the program. From the debuger you can also examine and change program variables in the middle of a program run, or execute any valid C statement. Besides being a reference for the SCI debug facility, this section will introduce you to general debugging strategies, and show you how you can use the SCI debuger to gain a better knowledge of C program flow. 17.1. Introduction The SCI debuger operates in what is known as "symbolic" mode. As you probably already know, a computer can not directly execute program instructions written in the C (or any other higher-level) language. The C language instructions must first be converted to machine language and then executed by the computer. This is the mode of operation when using a C compiler. Alternatively, the C source code can be directly executed by a program known as an "interpreter", which is exactly how SCI works. A C program that has been compiled is completely unreadable by us humans - all resemblence to the original C code has been stripped from the program since it is intended only for the computer's "eyes". We say that the "symbolic" representation of a machine readable program has been removed. On the other hand, since an interpreter always keeps a "symbolic" (human readable) form of your program in memory, it is very easy to follow the program as it is being executed by the interpreter. A debuger that has this ability to let the human reader follow along as the program is executed by the computer, is known as a "symbolic debuger". There are basically two types of program errors that can occur: unrecoverable and recoverable. Unrecoverable errors are typified by the computer's refusal to answer to the programmer's desperate pounding on the keyboard - we say that the computer has "locked up" and gone south for the winter. These errors may be caused by partial or complete destruction of the program itself, or of the operating system and usually require you to turn the computer off and then on again. Recoverable errors are the kind which do not - 68 - Small C Interpreter Programmer's Manual allow the program to run to normal completion and return you to either the operating system or to the calling program, or simply "get stuck" in a never ending loop. The category of recoverable errors also include incorrect results: YOU: what is 2 plus 2? COMPUTER: 5 and unexpected results: COMPUTER: shall I delete this file? YOU: No COMPUTER: OK, file deleted! For obvious reasons, SCI's built-in debuger is only capable of dealing with recoverable errors. The apporach to finding both of these types of errors is basically the same: allow the program to run normally up to the point just before it goes berzerk, then stop and look at how it got there. Usually, the hardest task is finding that point where your program goes over the edge. You have two choices: either run the program from the very beginning, one line at a time until something unexpected happens, or allow the program to run normally and stop just before the section of code that is suspect. The method of executing a program a line at a time is known as "single-stepping". Running a program normally and having it stop at a given line is known as "running to breakpoint". The SCI debuger allows you to use both of these approaches in any combination. 17.2. Enabling the Debuger The Library Function "trace" is used to turn the SCI debuger on and off and may be called either from the shell prompt or from within your program. A single argument to "trace" determines whether the debuger will be turned on or off: if the argument is non-zero the debuger is turned on; if zero, it is turned off. Thus, your program would look like this: - 69 - Small C Interpreter Programmer's Manual func() { int i; . . . trace(1); # turn debuger ON while(i<10) # scrutinize this loop { . . . } trace(0); # turn debuger OFF again } You can also turn the debuger on directy from the keyboard while a program is running. By pressing the <ESCAPE> key at any time, the program is stopped in mid execution and the debuger is turned on. Thus, if you have a program that seems to be stuck in a forever loop, you can get control and take a look at what's causing the problem. When the debuger gets control of your program, it will automatically display the line number and program text of the next line to be executed. It is important to realize that the displayed program line has not yet been executed. Directly below the displayed line is a circumflex that points the first item in the line that will be executed. For example, if you had more than one statement on a single line, you might see: 12: i = 10; putd(i); ^ The debuger then displays its question mark (?) prompt and waits for you to enter a command. Debuger commands always start with a dot (.) in the first column, followed by a command mnemonic letter. You can also enter a C statement at the debuger's "?" prompt and have it evaluated and the results displayed, just like in the shell. We will now walk through a sample program using the debuger as a way of introducing you to the debuger commands. - 70 - Small C Interpreter Programmer's Manual 17.3. Sample Debug Session If you haven't done so already, list the sample program that came with your distribution disk, CALC.SCI, either on your printer or "TYPE" it out on your screen. This is a simple integer calculator program that does addition, subtraction, multiplication and division. At the shell prompt, load CALC.SCI then type "calc()" to start the program. The program displays its prompt (->) and waits for you to enter a command. Try entering some mathematical expressions: > load calc.sci > calc() -> 2+2 4 -> 2+3*4 14 -> 3*4+2 14 -> 2-30/2 -13 Notice that the program is smart enough to know that multiplication and division have higher precedence than addition and subtraction. To get out of the program and back to the shell, type an "x": -> x 0 > Now, let's try the same scenario but this time turn on the SCI debuger before you start the calculator: > trace(1) 0 > calc() cmd:calc() ^ ? The debuger displays the C statement you entered on the shell's command line and prompts you with its "?" prompt - 71 - Small C Interpreter Programmer's Manual and waits for you to enter a command. For now, just type a few <RETURN>'s: ? 4:calc() ^ ? 5:{ ^ ? 6: char line[ 80 ]; ^ ? 8: Stacktop = 10; ^ ? 9: while(1) ^ ? The program is being executed one line at a time each time a <RETURN> is hit. Notice that each line is displayed preceded by the line number of the program. The statement you entered from the shell that started up the calculator is not a part of the program, and instead was preceded with a "cmd:" to indicate this fact. 17.3.1. Exiting the Debuger To halt the program and return back to the shell, use the debuger's "quit" command: ? .q 0 > Now we're back to the shell's prompt. The ".q" command stopped the program and turned the debuger off. Since we want to experiment some more, turn the debuger back on again and start up the program: - 72 - Small C Interpreter Programmer's Manual > trace(1) 0 > calc() cmd:calc() ^ ? 17.3.2. Single Stepping You can execute more than one program line at a time with the "step" command. At the "?" prompt, type ".s" followed by the number of program lines you want to execute: ? .s 4 9: while(1) ^ ? The debuger executed 4 lines, then stopped. This is useful when you want to get through a section of code quickly without having to hit <RETURN> and waiting for each line to be displayed. The "continue" command is equivalent to a ".s" with an infinitely large step count: ? .c -> 2+2 4 -> The program appears to be running slower than when it was run with the debuger turned off. This is because the debuger is still in control of the program, and must examine each line before it is executed. The usefulness of the ".c" command will become apparent later when we discuss breakpoints. To return back to the debuger prompt, hit an <ESCAPE> while the program is running. If the program is waiting for input from the console, hitting the <ESCAPE> key will have no effect. So type some mathematical expression as before, hit a <RETURN> and then quickly hit the <ESCAPE> key: - 73 - Small C Interpreter Programmer's Manual -> 2+3*4 interrupt 36: while(1) ^ ? When the <ESCAPE> is hit, the debuger displays an "interrupt" message, followed by the program line it was currently working on. 17.3.3. Displaying Global Variables At any time the debuger is waiting for input you may display all of the program's global variables and their contents with the "global" command: ? .g char *Lineptr (0xc334) = "2+3*4" int Stack[10] (0xc320) = 4 2 0 0 0 0 0 0 0 0 int Stackpt = 0 int Stackto = 10 ? The ".g" command displays each variable along with its data type ("char" or "int"). If the variable is an array or a pointer, its address is also printed in hexadecimal, for example (0xc352). Following that, the variable's value is displayed. If the variable is an array or a pointer, the first ten items in the array are displayed. Character arrays are printed as strings, integer arrays as a series of decimal numbers. Another form of the ".g" command, ".G", will display all of the program's functions and their program line numbers in addition to global variables: - 74 - Small C Interpreter Programmer's Manual ? .G char *Lineptr (0xc334) = "2+3*4" int Stack[10] (0xc320) = 4 2 0 0 0 0 0 0 0 0 int Stackpt = 0 int Stackto = 10 4:calc() 22:number() 32:addition() 57:multiplication() 82:push( n ) 89:pop() 96:isdigit( c ) ? 17.3.4. Breakpoints Next we will discuss one of the most powerful features of the debuger: breakpoints. Let's say we wanted to stop the program every time the functions "push" and "pop" were called, so that we could inspect the program's state. Looking at the debuger's output from the ".G" command above, we see that these functions are located at lines 82 and 89 respectively. To set breakpoints at these line numbers, we would enter the following two commands: ? .b 82 breakpoint set: 82:push( n ) ? .b 89 breakpoint set: 89:pop() ? The debuger prints the program line at which the breakpoint is set for verification. You may set a maximum of 5 breakpoints at any one time. To display all of the breakpoints that are currently set, use the ".B" command: ? .B 82:push( n ) 89:pop() ? - 75 - Small C Interpreter Programmer's Manual Now we can continue executing the program normally and it should stop as soon as either the "push" or "pop" functions are called. This is where the ".c" command is used: ? .c breakpoint: 82:push( n ) ^ ? As soon as a breakpoint is reached, the debuger announces this fact and displays the program line at the breakpoint. To delete a breakpoint, use the "delete breakpoint" command: ? .d 82 breakpoint deleted: 82:push( n ) ? Again, the program line at which the breakpoint was deleted is displayed for verification. When a breakpoint is deleted, the debuger will no longer stop at this program line after a ".c" command. To delete all breakpoints set, use the ".D" command: ? .D all breakpoints deleted ? 17.3.5. Function Call Trace Back Using breakpoints we can be certain of only one fact: the program started at point "A", and stopped at point "B". We know nothing about the route it took in getting there. The debuger's "trace back" command at least tells us the order of function calls that got us to point "B": Continuing with our debuging session, type the following command: - 76 - Small C Interpreter Programmer's Manual ? .t 82:push( n ) 22:number() 57:multiplication() 32:addition() 4:calc() ? The function call trace back printed by the ".t" command is read backwards from bottom to top. In other words in the above display, the function "calc" (which is the starting point) called "addition", which in turn called "multiplication", and so on. A variation of the "trace back" command, ".T", will also display all local variables and their contents for each function in the trace back: ? .T 82:push( n ) int n = 2 22:number() 57:multiplication() int num = 0 32:addition() int num = 0 4:calc() char line[80] (0xc334) = "2+3*4" ? The local variables are displayed in a similar format as for the ".g" command. 17.3.6. Examine a Program You may also use the SCI editor to examine your program. The editor will not allow you make any changes when invoked from the debuger, since this could completely alter the state of the current program run. To "examine" your program, type: ? .e The screen is erased and the editor is started up with the cursor resting on the line in the program that is to be - 77 - Small C Interpreter Programmer's Manual executed next. You may move about freely in the editor, but you may not make any changes. When you exit the editor (with a ^Z) the debuger knows which line the cursor was on when you left the editor, and you may set a breakpoint at that line by just giving the _______ ".b" command without a line number. - 78 - Small C Interpreter Programmer's Manual 18. The Shell This section will discuss in detail the operation of the program found in the file SHELL.SCI. We will also show you how to customize the shell program to suit your needs. If you haven't done so already, print out the shell program file or "TYPE" it out on your console screen. As you can see there are basically 2 sections of this program: the first section declares all of the Library Functions ("sys" call interfaces), The second section starts immediately after the "entry" keyword with the function "main()". This is the function that is executed after SHELL.SCI has been loaded into memory. Let's examine this function more closely now: - 79 - Small C Interpreter Programmer's Manual 43: entry 44: 45: char ln[80]; 46: char pr[20000]; 47: 48: main() 49: { 50: int f, t; 51: 52: puts(sys(0)); 53: puts("\nShell V1.3 15Mar86 Copyright (C) 1986 Bob Brodt\n"); 54: _nr=25; _nc=80; 55: _ro=_co=1; 56: _cp="\033[%d;%dH"; 57: _el="\033[K"; 58: _mhz=5; 59: *pr='Z'; 60: 61: for(;;) { 62: puts("> "); 63: ln[5]=0; 64: if(gets(ln)) { 65: if (!strncmp(ln,"edit",4)) 66: sys(atoi(ln+4),pr,19); 67: else if (!strncmp(ln,"list",4)) { 68: f=1; 69: t=32765; 70: if(ln[4]) 71: sscanf(ln+4,"%d %d",&f,&t); 72: sys(pr,f,t,27); 73: } 74: else if (!strncmp(ln,"save",4)) 75: sys(ln+5,pr,26); 76: else if (!strncmp(ln,"load",4)) 77: sys(ln+5,pr,25); 78: else if (!strcmp(ln,"exit")) 79: exit(); 80: else 81: printf("\n%d\n",sys(ln,pr,16)); 82: } 83: } 84: } Note that we have included line numbers here for reference. The data declarations at lines 45 and 46 are the shell's input line buffer (ln[80]) and user program buffer (pr[20000]) respectively. Lines 52 and 53 of course print the program identification banners. Lines 54 through 58 assign the editor's customization variables (for the IBM PC - 80 - Small C Interpreter Programmer's Manual in this version). Line 61 starts a "forever" loop that can only terminated by the call to the function "exit()" at line 79. This loop starts out by displaying the shell prompt ("> ") on the console screen, then waiting for a line of input from the console keyboard. The input line buffer stores the C statement read in from the console at line 64. It is then compared to each of the strings "edit", "list", "save", "load" and "exit". If the first four characters in the input buffer don't match any of these strings, the line is assumed to be a C statement and handed off to the interpreter (via "sys" function 16) for execution. The program buffer, "pr" is used to store the user's program functions and variables. The user can enter data into this buffer only by way of the SCI program editor ("sys" function 19). In fact, the program buffer is completely hidden from the user - any attempt to reference it via a C statement (for example "putchar( pr[0] )") will result in an "undefined symbol" error message. The user's program in the "pr" buffer is in "tokenized" form. That is, each language element (variables, keywords, punctuation, etc.) has been encoded so that it can be more easily and quickly recognized by the interpreter. The tokenized form of a program bears almost no resemblance to the human-readable form and should not be tampered with. 18.1. Customizing the Shell Now we will show you how you can customize this program. Start up SCI and when the shell's prompt appears, enter the command: > load shell.sci to load the shell file. Now edit the program from SCI's editor and remove all lines from the beginning of the program up to and including the "entry" keyword. Next let's change the string on line 62 (above) to something like: "yes, dear? ". Finally, replace the "exit()" on line 79 with a "return". Exit the editor and from the shell prompt type: > main() You should see the program identification banner again - 81 - Small C Interpreter Programmer's Manual and the new shell's prompt, "yes, dear? "! You can now do everything from this new shell that you did from the original shell - write programs with the editor, save them, list them and load them. When you type "exit" to this new shell however, you are returned to the original shell because we replaced the "exit to DOS" function call with a "return" to caller. Since the caller was the original shell, you are returned to its "> " prompt. Type an "exit" now to get back to the first shell and from there do a "save newshell". Then type "main()" again to get the "yes, dear? " shell. From here, type "load newshell" to load the newshell program. Edit the newshell program and change the "yes, dear? " prompt to something like: "you again? ". Now exit the editor and at the "yes, dear? " prompt type "main()". You should again see the program logon banner and the new shell prompt "you again? ", like this: yes, dear? main() Small C Interpreter V1.3 15Mar86 Copyright (C) 1986 Bob Brodt Shell V1.3 15Mar86 Copyright (C) 1986 Bob Brodt you again? In all, we now have 3 different shell programs running, one on top of the other, and we could actually continue doing this until we run out of memory! This is exactly analagous to the layers of an onion: each layer gets smaller as you go towards the center of the onion, just as the amount of usable memory becomes less as each new shell program is loaded from the previous shell. Now return to the original shell like so: you again? exit 0 yes, dear? exit 0 > It now becomes an easy task to customize the shell program to your heart's content using the SCI editor, test it from the SCI interpreter environment and when it's fully debuged, save it to disk. Of course you must remember to insert the Library Function declarations and the "entry" keyword before the new shell "main()" function if you intend to replace SHELL.SCI with the new program. - 82 - Small C Interpreter Programmer's Manual As an exercise, add a directory listing command to the shell, using the following program as a guide. If are having difficulty, you may peek at the answers on the next page... dir(pat) { char file[16]; int t; t=0; if(pat) f=scandir(pat,file); else f=scandir("*.*",file); while(f) { printf("%-20s",file); ++t; f=scandir(0,file); } if(t%4) putchar('\n'); } - 83 - Small C Interpreter Programmer's Manual . . . exit(); else if (!strncmp(ln,"dir",3)) { char file[16]; t=0; if(ln[3]) f=scandir(ln+4,file); else f=scandir("*.*",file); while(f) { printf("%-20s",file); ++t; f=scandir(0,file); } if(t%4) putchar('\n'); } else . . . 18.2. DOS Command Line Arguments to the Shell A mechanism has been provided to pass operating system command line arguments to the shell in a way similar to most commercially available C compilers. By specifying a "-A" on the MS-DOS command lines, all arguments to the right of the "-A" will be ignored by SCI and instead passed to the shell program. SCI always passes two arguments to the "entry" program in the startup file, although the program is free to use or ignore these arguments. These are: a count of the number of arguments following the "-A" option on the DOS command line and; A pointer to the array of strings that contain these arguments. These arguments are commonly declared as "argc" (argument count) and "argv" (argument vector) in the C community. Make the following changes and additions to the program in SHELL.SCI: - 84 - Small C Interpreter Programmer's Manual . . . main(argc, arv) int argc, *argv; { int i; while ( i<argc ) { puts(argv[i++]); putchar('\n'); } . . . } Then, when the following command is entered at the operating system level: A>SCI -A Hello out there! the shell program would start up like this: Hello out there! Small C Interpreter V1.3M 15Mar86 Copyright (C) 1986 Bob Brodt Shell V1.3M 15Mar86 Copyright (C) 1986 Bob Brodt > Note that since SCI does not support pointers to pointers, the "argv" variable must be declared as a pointer to "int". Then, each "argv[i]" is a pointer to a string that points to one of the words passed on the command line. - 85 - əəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəə